home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 July / EnigmA AMIGA RUN 20 (1997)(G.R. Edizioni)(IT)[!][issue 1997-07 & 08][EAR-CD IV].iso / earcd / dev / c / vbcc.lha / readme.vbcc next >
Text File  |  1997-03-01  |  15KB  |  508 lines
  1.  
  2.  
  3. vbcc - portable ANSI C compiler (c) in 1995-97 by Volker Barthelmann
  4.  
  5.  
  6. INTRODUCTION
  7.  
  8.     vbcc is a free portable and retargetable ANSI C compiler.
  9.  
  10.     This archive contains the compiler, preprocessor, assembler, linker,
  11.     frontend, message browser, startup codes, C-libraries, amiga.lib
  12.     replacement as well as several other tools (mostly with complete source).
  13.  
  14.     This gives you a complete system that allows to develop programs in
  15.     ANSI C as well as Amiga-specific programs (provided you obtain the
  16.     OS-includes).
  17.  
  18.     All major parts of this distribution (including compiler, preprocessor,
  19.     libraries etc.) have been compiled/assembled with this system and
  20.     apart from the OS-includes everything is included to rebuilt vbcc,
  21.     the libraries and many of the other programs.
  22.  
  23.  
  24. FEATURES
  25.  
  26.     vbcc..
  27.  
  28.     - comes with source
  29.  
  30.     - is free
  31.  
  32.     - is portable and retargetable
  33.  
  34.     - comes with a global optimizer that can e.g. do global common
  35.       subexpression elimination, constant propagation, function inlining
  36.       and several other optimizations (but is not yet finished and may
  37.       have some bugs)
  38.  
  39.     - should be ANSI compliant
  40.  
  41.     - can generate code that runs on a plain 68000 CPU
  42.  
  43.     - can generate code optimized for 020/030, 040 or 060
  44.  
  45.     - can generate code that uses the 68881/2, 68040/060 FPUs directly
  46.       and comes with appropriate math-libraries
  47.  
  48.     - generates standard Amiga object files
  49.  
  50.     - does not need too much memory
  51.  
  52.     - comes with a message browser
  53.  
  54.     - comes with a config program
  55.  
  56.     - offers a lot of error/warning messages that can be turned on/off
  57.       separately
  58.  
  59.  
  60. REQUIREMENTS
  61.  
  62.     To use vbcc you need:
  63.  
  64.     - an Amiga with OS 2.0 or higher (programs compiled with vbcc probably
  65.       work under earlier OS-versions, too)
  66.  
  67.     - enough RAM (it is possible to translate small programs with 1MB, but
  68.       for larger programs much more will be needed)
  69.  
  70.     Stuff that is not needed, but may be very useful:
  71.  
  72.     - harddisk
  73.  
  74.     - editor
  75.  
  76.     - make, touch etc.
  77.  
  78.     - the Amiga OS-includes (they can be found on certain CDs and on
  79.       some ftp-servers which have those CDs mounted)
  80.  
  81.     - pipe-command (to use the message browser)
  82.  
  83.     Also you should know how to use the shell and you should know ANSI C
  84.     (if you need a book I recommend (like everyone) "The C Programming
  85.     Language, Second Edition, ANSI C" by Kernighan and Ritchie).
  86.  
  87.  
  88. LEGAL
  89.  
  90.     Note that this distribution contains several programs, libraries etc.
  91.     that are from different authors and are under different legal status.
  92.     So always read the corresponding doc/guide-file to find out under
  93.     what conditions a certain file may be used, distributed etc.
  94.  
  95.     For the most part you can assume that you may use everything for
  96.     non-commercial purposes and may distribute the unchanged archive
  97.     in whole.
  98.  
  99.     Changing any parts from this archive, distributing parts of it or
  100.     using it commercially might be legal for certain parts, but illegal
  101.     for others, so read all docs carefully before doing any of the above.
  102.  
  103.     This archive contains code written by (this list may be incomplete):
  104.  
  105.     Volker Barthelmann, Frank Wille, Thorsten Schaaps, Dennis Ritchie,
  106.     Matthias Fleischer, Gunther Nikl, Mike Schwartz, Kasper Graversen,
  107.     Johnny Tevessen
  108.  
  109.     However, if you have any comments/problems etc. with anything, please
  110.     do not bother them, but write to me (volker@vb.franken.de) first.
  111.     Exceptions are the parts by Kasper Graversen.
  112.  
  113.  
  114. INSTALLATION/TUTORIAL
  115.  
  116.     The first step (which you probably already did) is to extract the
  117.     entire archive (take care to preserve the file attributes).
  118.  
  119.     The distributed programs are for the most part only usable from a shell.
  120.  
  121.     To use vbcc the following steps are necessary:
  122.  
  123.     1. Assign vbcc: to the subdirectory vbcc/machines/amiga68k.
  124.  
  125.     2. Assign vlib: to vbcc:lib.
  126.  
  127.     3. Assign vinclude: to vbcc:include.
  128.  
  129.        If you have the OS-includes you can either add the path to this
  130.        assign, e.g.
  131.  
  132.         assign vinclude: vbcc:include myhd:os-includes
  133.  
  134.        or you can modify the vc.config (see below).
  135.  
  136.        If you want to use ixemul.lib assign ixinclude: to the directory
  137.        containing the ixemul-includes.
  138.  
  139.     4. Add vbcc://bin to your path.
  140.  
  141.     5. set the stack to a reasonable value (perhaps some 10k).
  142.  
  143.     If you use vbcc frequently it is probably a good idea to add those
  144.     commands to your user-startup, shell-startup or similar.
  145.     However if you just want to try it out the sample script init_vbcc in
  146.     the subdirectory machines/amiga68k does all this for you.
  147.     You have to cd in its directory and start it from there, e.g.:
  148.  
  149.         cd myhd:vbcc/machines/amiga68k
  150.         init_vbcc
  151.  
  152.     Now you should be able to use vbcc. E.g. if you want to compile and
  153.     link the program hello.c you can type
  154.  
  155.         vc hello.c
  156.  
  157.     This will compile and link the file hello.c and create the executable
  158.     a.out in the current directory.
  159.  
  160.         vc hello.c -o hello
  161.  
  162.     will do the same, but the created executable will be called hello.
  163.  
  164.         vc -c t1.c t2.c
  165.  
  166.     will compile t1.c and t2.c without linking, creating the object files
  167.     t1.o and t2.o.
  168.  
  169.         vc t1.o t2.o -o tt
  170.  
  171.     will link them together and create the executable tt.
  172.  
  173.     If your program uses floating point add -lmieee to the commandline
  174.     to link with the math-library, e.g.:
  175.  
  176.         vc calc.c -o calc -lmieee
  177.  
  178.     There is also an extra.lib which includes a few functions that are
  179.     no standard ANSI functions but some people seem to regard them as
  180.     standard functions. If you use one of these add -lextra to the
  181.     commandline and read:
  182.  
  183.         vbcc/machines/amiga68k/doc/extralib.doc
  184.  
  185.     (Note that IMHO it is often a bad idea to use those functions.)
  186.  
  187.     For further information read the files:
  188.  
  189.         vbcc/doc/vbcc.doc
  190.         vbcc/doc/vc.doc
  191.         vbcc/doc/vbccamiga68k.doc
  192.         vbcc/machines/amiga68k/doc/vclib.doc
  193.  
  194.  
  195. CONFIGURATION
  196.  
  197.     The frontend searches for a file vc.config in ENV: and vbcc: to read
  198.     preferences. The provided sample vc.config should be usable and does
  199.     not have to be changed but you can add something to suit your personal
  200.     preferences - read
  201.  
  202.         vbcc/doc/vc.doc
  203.  
  204.     to find out more.
  205.  
  206.     If you have the OS-includes and do not want to add them to the vinclude:
  207.     assign mentioned above you can also modify the vc.config file:
  208.  
  209.     Add -I<full_path> directly after the two occurences of -Ivinclude: in
  210.     the sample vc.config, e.g.:
  211.  
  212.         -pp=vcpp -Ivinclude: -Imyhd:os-include -D__STDC__=1 %s %s %s
  213.         -ppv=vcpp -Ivinclude: -Imyhd/os-include -D__STDC__=1 %s %s %s
  214.  
  215.  
  216.     There is a smaller version of vbcc which does not contain the optimizer.
  217.     If you do not intend to use the optimizer or have tight memory you can
  218.     replace every 'vbcca68k' in the config-file you use by 'vbccsa68k'.
  219.  
  220. MESSAGE BROWSER
  221.  
  222.     If you start the message browser with
  223.  
  224.         run vbrowse
  225.  
  226.     it will open a window with a listview gadget. If you have a pipe
  227.     command installed you can now invoke vc via tovbr, e.g.
  228.  
  229.         tovbr vc hello.c
  230.  
  231.     and any output from vc will be displayed in the window of vbrowse
  232.     rather than in the shell. It might be convenient to make an alias like
  233.  
  234.         alias vb tovbr vc
  235.  
  236.     so that invoking vb will automatically display the output in the browser.
  237.  
  238.     If there is an error/warning-message in the browser you can invoke a
  239.     configurable command by double-clicking on the message.
  240.  
  241.     Double-clicking on the quoted line will invoke GoldEd (if you have it
  242.     installed) by default, load the file that caused the error and the cursor
  243.     will be placed on this line in the default configuration. If you use
  244.     another editor or want to change this behaviour have a look at
  245.     vbcc/machines/amiga68k/doc/vbrowse.doc.
  246.  
  247.     Double-clicking on the error-line (the one below the quoted line) will
  248.     invoke the command showerr that will open the VBCCMessages.guide and
  249.     display a more detailed description of the error (if there is one in
  250.     the guide - there are not yet descriptions for all messages).
  251.  
  252.     Read vbcc/machines/amiga68k/vbrowse.doc for further information.
  253.  
  254.  
  255. CONTENTS
  256.  
  257.     This archive contains (among others) the following files and directories:
  258.  
  259.     vbcc/
  260.  
  261.             The main directory. The source files for the compiler and the
  262.             builtin preprocessor by Thorsten Schaaps are here.
  263.  
  264.     vbcc/doc/
  265.  
  266.             Host independant documentation for the compiler is in this dir.
  267.  
  268.     vbcc/doc/History
  269.  
  270.             Changes in since earlier versions of the compiler.
  271.  
  272.     vbcc/doc/vbcc.doc
  273.  
  274.             Documentation for the target-independant part of the compiler.
  275.  
  276.     vbcc/doc/errors.doc
  277.  
  278.             A list of all error/warning-messages from the compiler -
  279.             sometimes with more detailed descriptions.
  280.  
  281.     vbcc/doc/vbccamiga68k.doc
  282.  
  283.             Documentation for the 68k code generator.
  284.  
  285.     vbcc/doc/vbcci386.doc
  286.  
  287.             Documentation for the i386 code generator.
  288.  
  289.     vbcc/doc/vc.doc
  290.  
  291.             Documentation for the compiler-frontend.
  292.  
  293.     vbcc/doc/vcpp.doc
  294.  
  295.             Some short comments regarding the preprocessor from the
  296.             lcc-distribution. Read the copyright-notice.
  297.  
  298.     vbcc/vcpp/
  299.  
  300.             The source for the external preprocessor by Dennis Ritchie.
  301.  
  302.     vbcc/bin/
  303.  
  304.             The directory containing binaries of preprocessor, compiler and
  305.             frontend. Additional binaries may be in machines/xyz/bin/.
  306.  
  307.     vbcc/bin/vbcca68k
  308.  
  309.             The C compiler with global optimizer.
  310.  
  311.     vbcc/bin/vbccsa68k
  312.  
  313.             A smaller version of the C compiler without optimizer.
  314.  
  315.     vbcc/bin/vc
  316.  
  317.             The compiler-frontend.
  318.  
  319.     vbcc/bin/vcpp
  320.  
  321.             The preprocessor from the lcc-distribution (by Dennis Ritchie).
  322.  
  323.     vbcc/machines/amiga68k/
  324.  
  325.             Everything that is specific to the Amiga68k is in this directory.
  326.  
  327.     vbcc/machines/amiga68k/doc/
  328.  
  329.             This contains documentation for the Amiga68k specific parts.
  330.  
  331.     vbcc/machines/amiga68k/doc/extralib.doc
  332.  
  333.             Documentation for extra.lib.
  334.  
  335.     vbcc/machines/amiga68k/doc/PhxAss.guide
  336.  
  337.             Documentation for the assembler by Frank Wille.
  338.  
  339.     vbcc/machines/amiga68k/doc/PhxLnk.guide
  340.  
  341.             Documentation for the linker by Frank Wille.
  342.  
  343.     vbcc/machines/amiga68k/doc/VBCCMessages.guide
  344.  
  345.             The vbcc/doc/errors.doc in Amigaguide-format (done by Walter
  346.             Doerwald).
  347.  
  348.     vbcc/machines/amiga68k/doc/vclib.doc
  349.  
  350.             Documentation for the Amiga-C-library.
  351.  
  352.     vbcc/machines/amiga68k/doc/ixemul.doc
  353.  
  354.             Documentation on using the ixemul.library.
  355.  
  356.     vbcc/machines/amiga68k/doc/vbrowse.doc
  357.  
  358.             Documentation on the message browser and several connected tools.
  359.  
  360.     vbcc/machines/amiga68k/doc/fd2lib.doc
  361.  
  362.             Documentation for fd2lib.
  363.  
  364.     vbcc/machines/amiga68k/doc/minstart.doc
  365.  
  366.             Documentation for minstart.o.
  367.  
  368.     vbcc/machines/amiga68k/doc/alib.doc
  369.  
  370.             Documentation for alib by Mike Schwartz.
  371.  
  372.     vbcc/machines/amiga68k/init_vbcc
  373.  
  374.             A sample script to do the necessary assigns etc. to use vbcc.
  375.  
  376.     vbcc/machines/amiga68k/include
  377.  
  378.             This directory contains the standard-ANSI-includes for vc.lib.
  379.  
  380.     vbcc/machines/amiga68k/bin/
  381.  
  382.             This directory contains all Amiga-specific executables.
  383.  
  384.     vbcc/machines/amiga68k/bin/PhxAss
  385.  
  386.             The assembler by Frank Wille.
  387.  
  388.     vbcc/machines/amiga68k/bin/PhxLnk
  389.  
  390.             The linker by Frank Wille.
  391.  
  392.     vbcc/machines/amiga68k/bin/vbrowse
  393.     vbcc/machines/amiga68k/bin/vsend
  394.     vbcc/machines/amiga68k/bin/tovbr
  395.     vbcc/machines/amiga68k/bin/showerr
  396.  
  397.             The message browser and some tools.
  398.  
  399.     vbcc/machines/amiga68k/bin/vconfig
  400.  
  401.             A user interface to edit the vc.config.
  402.  
  403.     vbcc/machines/amiga68k/bin/fd2lib
  404.  
  405.             fd2lib generates stubs for shared libraries and must be used to
  406.             rebuilt amiga.lib or if you want to use any custom shared-library.
  407.  
  408.     vbcc/machines/amiga68k/bin/alib
  409.  
  410.             Used to create link-libraries.
  411.  
  412.     vbcc/machines/amiga68k/lib/
  413.  
  414.             This directory contains the link-libraries and startup-codes.
  415.  
  416.     vbcc/machines/amiga68k/lib/startup.o
  417.  
  418.             The standard startup-code for vc.lib.
  419.  
  420.     vbcc/machines/amiga68k/lib/vc.lib
  421.  
  422.             The standard C-library.
  423.  
  424.     vbcc/machines/amiga68k/lib/vcs.lib
  425.  
  426.             The small data C-library.
  427.  
  428.     vbcc/machines/amiga68k/lib/mieee.lib
  429.  
  430.             Math-library that uses the MathIeee-libraries.
  431.  
  432.     vbcc/machines/amiga68k/lib/m881.lib
  433.  
  434.             Math-library that uses FPU-instructions of the 68881/2.
  435.  
  436.     vbcc/machines/amiga68k/lib/m040.lib
  437.  
  438.             Math-library that uses FPU-instructions that do not have to be
  439.             emulated on a 68040 and the Motorola emulation routines
  440.             otherwise.
  441.  
  442.     vbcc/machines/amiga68k/lib/m040o.lib
  443.  
  444.             Math-library that uses FPU-instructions that do not have to be
  445.             emulated on a 68040 and the MathIeee*.library functions
  446.             otherwise.
  447.  
  448.     vbcc/machines/amiga68k/lib/crt0.o
  449.  
  450.             Startup-code for using ixemul.library with large data model.
  451.  
  452.     vbcc/machines/amiga68k/lib/bcrt0.o
  453.  
  454.             Startup-code for using ixemul.library with small data model.
  455.  
  456.     vbcc/machines/amiga68k/lib/ixemul.lib
  457.  
  458.             Stub library for using ixemul.library with large data model.
  459.  
  460.     vbcc/machines/amiga68k/lib/ixemuls.lib
  461.  
  462.             Stub library for using ixemul.library with small data model.
  463.  
  464.     vbcc/machines/amiga68k/lib/amiga.lib
  465.  
  466.             Replacement for the standard amiga.lib.
  467.  
  468.     vbcc/machines/amiga68k/lib/amigas.lib
  469.  
  470.             Small data replacement for the standard amiga.lib.
  471.  
  472.     vbcc/machines/amiga68k/lib/minstart.o
  473.  
  474.             Small startup-code for small programs that do not use functions
  475.             from the C-library.
  476.  
  477.     vbcc/machines/amiga68k/lib/extra.lib
  478.  
  479.             Very small library containing a few functions some people want.
  480.  
  481.     vbcc/machines/amiga68k/lib/extras.lib
  482.  
  483.             Small data version of the above.
  484.  
  485.  
  486.  
  487. BUGREPORTS/COMMENTS
  488.  
  489.     If you think vbcc generates bad code, throws enforcer hits, crashes,
  490.     seems to be not ANSI-compliant etc. and the problem is not mentioned
  491.     anywhere in this docs as known problem, please send a mail with your
  492.     system configuration, the vbcc version, the command line you used, the
  493.     source that caused the problem and a brief description of the problem to
  494.  
  495.         volker@vb.franken.de
  496.  
  497.     Also if you find problems with the includes, the libraries or you have
  498.     suggestions, dislikes etc. send me a mail.
  499.     Corrections, improvements etc. of the manuals are appreciated, too.
  500.  
  501.  
  502.  
  503. Volker Barthelmann                                      volker@vb.franken.de
  504. Kennedy-Ring 39
  505. 91301 Forchheim
  506. Germany
  507.  
  508.